<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Tomcat 4 - Class Loader HOW-TO</title><meta name="author" value="Craig R. McClanahan"><meta name="email" value="craigmcc@apache.org"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./../images/tomcat.gif" align="right" alt="
      The Tomcat Servlet/JSP Container
    " border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 4</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top" nowrap="true"><h1>Class Loader HOW-TO</h1></td><td align="right" valign="top" nowrap="true"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Quick Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>

<p>The following rules cover about 95% of the decisions that application
developers and deployers must make about where to place class and resource
files to make them available to web applications:</p>
<ul>
<li>For classes and resources specific to a particular web application,
    place unpacked classes and resources under <code>/WEB-INF/classes</code>
    of your web application archive, or place JAR files containing those
    classes and resources under <code>/WEB-INF/lib</code> of your web
    application archive.</li>
<li>For classes and resources that must be shared across all web applications,
    place unpacked classes and resources under
    <code>$CATALINA_BASE/shared/classes</code>, or place JAR files
    containing those classes and resources under
    <code>$CATALINA_BASE/shared/lib</code>.</li>
</ul>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>

<p>Like many server applications, Tomcat 4 installs a variety of class loaders
(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
different portions of the container, and the web applications running on the
container, to have access to different repositories of available classes and
resources.  This mechanism is used to provide the functionality defined in the
Servlet Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>

<p>In a Java 2 (that is, JDK 1.2 or later) environment, class loaders are
arranged in a parent-child tree.  Normally, when a class loader is asked to
load a particular class or resource, it delegates the request to a parent
class loader first, and then looks in its own repositories only if the parent
class loader(s) cannot find the requested class or resource.  The model for
web application class loaders differs slightly from this, as discussed below,
but the main principles are the same.</p>

<p>When Tomcat 4 is started, it creates a set of class loaders that are
organized into the following parent-child relationships, where the parent
class loader is above the child class loader:</p>

<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
      Bootstrap
          |
       System
          |
       Common
      /      \
 Catalina   Shared
             /   \
        Webapp1  Webapp2 ... 
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>

<p>The characteristics of each of these class loaders, including the source
of classes and resources that they make visible, are discussed in detail in
the following section.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Class Loader Definitions"><strong>Class Loader Definitions</strong></a></font></td></tr><tr><td><blockquote>

<p>As indicated in the diagram above, Tomcat 4 creates the following class
loaders as it is initialized:</p>
<ul>
<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
    classes provided by the Java Virtual Machine, plus any classes from JAR
    files present in the System Extensions directory
    (<code>$JAVA_HOME/jre/lib/ext</code>).  <em>NOTE</em> - Some JVMs may
    implement this as more than one class loader, or it may not be visible
    (as a class loader) at all.</li>
<li><strong>System</strong> - This class loader is normally initialized from
    the contents of the <code>CLASSPATH</code> environment variable.  All such
    classes are visible to both Tomcat internal classes, and to web
    applications.  However, the standard Tomcat 4 startup scripts
    (<code>$CATALINA_HOME/bin/catalina.sh</code> or
    <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
    of the <code>CLASSPATH</code> environment variable itself, and instead
    build the System class loader from the following repositories:
    <ul>
    <li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main() method
        that is used to initialize the Tomcat 4 server, and the class loader
        implementation classes it depends on.</li>
    <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler used
        to convert JSP pages into servlet classes.</li>
    </ul></li>
<li><strong>Common</strong> - This class loader contains additional classes
    that are made visible to both Tomcat internal classes and to all web
    applications.  Normally, application classes should <strong>NOT</strong>
    be placed here.  All unpacked classes and resources in
    <code>$CATALINA_HOME/common/classes</code>, as well as classes and
    resources in JAR files under the
    <code>$CATALINA_HOME/commons/endorsed</code> and
    <code>$CATALINA_HOME/common/lib</code> directories,
    are made visible through this
    class loader.  By default, that includes the following:
    <ul>
    <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
        classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
        are included automatically on JDK 1.3 and later).</li>
    <li><em>naming-common.jar</em> - The JNDI implementation used by Tomcat 4
        to represent in-memory naming contexts.</li>
    <li><em>naming-resources.jar</em> - The specialized JNDI naming context
        implementation used to represent the static resources of a web
        application.</li>
    <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
    <li><em>xerces.jar</em> - The XML parser that is visible by default to
        Tomcat internal classes and to web applications.  This can be
        overridden, for a particular web application, by including your
        desired parser in <code>/WEB-INF/lib</code>.</li>
    </ul></li>
<li><strong>Catalina</strong> - This class loader is initialized to include
    all classes and resources required to implement Tomcat 4 itself.  These
    classes and resources are <strong>TOTALLY</strong> invisible to web
    applications.  All unpacked classes and resources in
    <code>$CATALINA_HOME/server/classes</code>, as well as classes and
    resources in JAR files under
    <code>$CATALINA_HOME/server/lib</code>, are made visible through
    this class loader.  By default, that includes the following:
    <ul>
    <li><em>catalina.jar</em> - Implementation of the Catalina servlet
        container portion of Tomcat 4.</li>
    <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
        <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
        regular expression processing library, used in the implementation of
        request filters.</li>
    <li><em>servlets-xxxxx.jar</em> - The classes associated with each
        internal servlet that provides part of Tomcat's functionality.
        These are separated so that they can be completely removed if the
        corresponding service is not required, or they can be subject to
        specialized security manager permissions.</li>
    <li><em>tomcat-coyote.jar</em> - Coyote connector for Tomcat 4.</li>
    <li><em>tomcat-http11.jar</em> - Standalone Java HTTP/1.1 
        connector.</li>
    <li><em>tomcat-jk.jar</em> - Classes for the Java portion of the
        <code>JK</code> web server connector, which allows Tomcat to
        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
    <li><em>tomcat-jk2.jar</em> - Classes for the Java portion of the
        <code>JK 2</code> web server connector, which allows Tomcat to
        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
    <li><em>tomcat-util.jar</em> - Utility classes required by some
        Tomcat connectors.</li>
    <li><em>tomcat-warp.jar</em> - Classes for the Java portion of the
        <code>Webapp</code> web server connector, using the WARP protocol
        which allows Tomcat to run behind the Apache HTTPD web server
        (1.3 and 2.0).</li>
    </ul></li>
<li><strong>Shared</strong> - This class loader is the place to put classes
    and resources that you wish to share across <strong>ALL</strong>
    web applications (unless Tomcat internal classes also need access,
    in which case you should put them in the <strong>Common</strong>
    class loader instead).  All unpacked classes and resources in
    <code>$CATALINA_BASE/shared/classes</code>, as well as classes and
    resources in JAR files under <code>$CATALINA_BASE/shared/lib</code>,
    are made visible through this class loader.  By default, that includes
    the following:
    <ul>
    <li><em>jasper-compiler.jar</em> - The page compiler classes required
        to convert JSP source pages into executable servlets and compile
        them.</li>
    <li><em>jasper-runtime.jar</em> - The runtime support classes required
        to execute JSP pages that have already been translated into Java
        servlets and then compiled.</li>
    <li><em>naming-factory.jar</em> - JNDI object factories for resources
        supported by the default JNDI naming context provided to web
        applications.</li>
    </ul></li>
<li><strong>WebappX</strong> - A class loader is created for each web
    application that is deployed in a single Tomcat 4 instance.  All unpacked
    classes and resources in the <code>/WEB-INF/classes</code> directory of
    your web application archive, plus classes and resources in JAR files
    under the <code>/WEB-INF/lib</code> directory of your web application
    archive, are made visible to the containing web application, but to
    no others.</li>
</ul>

<p>As mentioned above, the web application class loader diverges from the
default Java 2 delegation model (in accordance with the recommendations in the
Servlet Specification, version 2.3, section 9.6).  When a request to load a
class from the web application's <em>WebappX</em> class loader is processed,
this class loader will look in the local repositories <strong>first</strong>,
instead of delegating before looking.  All other class loaders in Tomcat 4
follow the usual delegation pattern.</p>

<p>Therefore, from the perspective of a web application, class or resource
loading looks in the following repositories, in this order:</p>
<ul>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
<li>Bootstrap classes of your JVM</li>
<li>System class loader classses (described above)</li>
<li><em>$CATALINA_HOME/common/classes</em></li>
<li><em>$CATALINA_HOME/common/endorsed/*.jar</em></li>
<li><em>$CATALINA_HOME/common/lib/*.jar</em></li>
<li><em>$CATALINA_BASE/shared/classes</em></li>
<li><em>$CATALINA_BASE/shared/lib/*.jar</em></li>
</ul>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="J2SE classes and extensions"><strong>J2SE classes and extensions</strong></a></font></td></tr><tr><td><blockquote>

<p>In addition to the previous rules, the web application classloader 
delegates classloading for classes which are part of J2SE (which means 
it will attempt loading first with its parent classloader before loading 
from its current repositories, regardless of the current delegation setting). 
This includes classes from the SAX and DOM APIs, Xalan, Xerces, 
and any classes which package name starts with "javax.".</p>

<p>The web application classloader will also refuse to load classes from the
core Java language ("java.*" packages).</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="XML Parsers and JDK 1.4"><strong>XML Parsers and JDK 1.4</strong></a></font></td></tr><tr><td><blockquote>

<p>Among many other changes, the JDK 1.4 release packages the JAXP APIs, and
a version of Xerces, inside the JDK.  This has impacts on applications that
wish to use their own XML parser.</p>

<p>In previous versions of Tomcat 4, you could simply replace the XML parser
in the <code>$CATALINA_HOME/common/lib</code> directory to change the parser
used by all web applications.  However, this technique will not be effective
when you are running on JDK 1.4, because the usual class loader delegation
process will always choose the implementation inside the JDK in preference
to this one.</p>

<p>JDK 1.4 supports a mechanism called the "Endorsed Standards Override
Mechanism" to allow replacement of APIs created outside of the JCP (i.e.
DOM and SAX from W3C).  It can also be used to update the XML parser
implementation.  For more information, see:
<a href="http://java.sun.com/j2se/1.4/docs/guide/standards/index.html">
http://java.sun.com/j2se/1.4/docs/guide/standards/index.html</a>.</p>

<p>Tomcat utilizes this mechanism by including the system property setting
<code>-Djava.endorsed.dirs=$CATALINA_HOME/common/endorsed</code> in the
command line that starts the container.  Therefore, you can replace the
parser that is installed in this directory, and it will get used even on a
JDK 1.4 system.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Running under a security manager"><strong>Running under a security manager</strong></a></font></td></tr><tr><td><blockquote>

<p>When running under a security manager the locations from which classes
are permitted to be loaded will also depend on the contents of your policy
file. See <a href="security-manager-howto.html">Security Manager HOW-TO</a>
for further information.</p>

</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2009, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>